Skip to content

Fix the Turn Envelope benchmark guide link in MkDocs - #9032

Merged
loopx-agent merged 2 commits into
mainfrom
codex/fix-turn-envelope-benchmark-guide-20261118
Nov 21, 2026
Merged

loopx-agent merged 2 commits into
mainfrom
codex/fix-turn-envelope-benchmark-guide-20261118

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

User impact

The Turn Envelope guide links to the benchmark runtime guide so readers can find the supported configurations. MkDocs only publishes files under docs/. The previous relative link crossed that boundary and failed the strict Frontstage Pages build. The new link opens the same guide in the LoopX repository.

The exact Frontstage Pages check failed on this link for #9013 and #9027. #9013 check · #9027 check

Validation

  • Reproduced the single strict-build warning on 4a0188c1ca1b.
  • The patched documentation site and both language editions of the book built in strict mode using the workflow's documentation requirements.
  • The built Turn Envelope page contains the guide's resolved GitHub URL, and GitHub confirms the target exists on main.
  • Public runtime artifacts still require the separate C1 default-contract qualification. The same qualification failure is present on the main branch. Main snapshot check

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent | model: Gemini | provider: Google | declaration_source: self_reported (host observation unavailable)

动机 / Motivation

受影响对象与触发任务:在 MkDocs 托管站点阅读 Turn Envelope 协议文档的读者,以及运行严格模式文档站点构建的维护者。

变更前后场景:修改前:docs/reference/protocols/turn-envelope-v0.md 第 627 行使用 ../../../benchmark/runtime/RUNTIME.md 相对路径,越出 mkdocs.yaml 的 docs_dir 根目录,导致严格文档构建报错断链。修改后:替换为指向 main 分支仓库文件的 GitHub URL,链接保持有效且不再越界。

可观测结果:相对越界链接替换为 origin/main 上已验证存在的 benchmark/runtime/RUNTIME.md 仓库 URL,docs-governance-smoke 与 canary premerge quick 在精确提交头通过。

边界与非目标(Non-goals):不将 benchmark 目录纳入 MkDocs docs_dir,不改变 Turn Envelope 协议语义,也不改动未进入站点构建告警的其他 RFC 文档链接。 若不做此修复,托管文档站点构建会在该越界链接处持续触发严格构建失败;作为单点文档链接修复切片,本 PR 完整关闭了该链接问题且无遗留缺口。

改动思路 / Approach

入口为托管文档 docs/reference/protocols/turn-envelope-v0.md 第 627 行(受 mkdocs.yaml 的 docs_dir: docs 边界约束)。权威真源方面,benchmark/runtime/RUNTIME.md 在 origin/main 上存在(git ls-tree origin/main benchmark/runtime/RUNTIME.md 为 100644 blob bc44dd1f)。仓库 docs/ 下已有多处采用 https://github.com/loopx-project/loopx/blob/main/... 指向 docs/ 外部路径的既有惯例,本次复用该约定,无需新增重定向脚本或同步副本;未引入任何运行时策略、状态转换或外部 IO,当前边界清晰聚焦于文档外链修复。

具体改动 / Changes

关键内容讲解

  • docs/reference/protocols/turn-envelope-v0.md (L624-L628):将 Benchmark Heartbeat Worker 说明段中的 [runtime guide](../../../benchmark/runtime/RUNTIME.md) 更新为 [runtime guide](https://github.com/loopx-project/loopx/blob/main/benchmark/runtime/RUNTIME.md),正文内其余指向 docs/ 内部的相对链接保持不变。
  • 规范对照:无独立前置书面 RFC 规范约束该外链写法(no_spec / spec_source: none),依据 mkdocs.yaml 站点目录边界与既有文档惯例判定。

对主干的风险 / Risks

无阻塞性发现(No blocking finding)。

  • 失败路径与负向核对:仅修改 1 行 Markdown 链接;仓库 origin/main 确认存在 benchmark/runtime/RUNTIME.md(blob bc44dd1f)。唯一外链失配假设是未来该文件从 main 删除或改名,届时仅影响该单条跳转且可单行回滚。
  • 本地验证矩阵(精确 head):
    • git diff --check origin/main...HEAD:PASS
    • python3 scripts/check_rfc_bilingual.py --base origin/main --head HEAD:PASS
    • python3 examples/docs-governance-smoke.py:PASS (docs-governance-smoke ok)
    • loopx check --scan-path docs/reference/protocols/turn-envelope-v0.md:PASS(0 errors / 0 warnings)
    • loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main:PASS (merge_gate_passed: true)
    • mkdocs build --strict:UNVERIFIED(本地 .venv 未安装 mkdocs 可执行程序;远端 CI 依策略不等待 ci_policy: not_consulted)。

我的整体评价 / Verdict

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

  • 成果影响(outcome_impact):
    • long_horizon: not_applicable —— 纯文档链接修复,不涉及控制平面状态、调度、续跑或重试链路。
    • user_experience: improved —— 修复 turn-envelope-v0.md 在 MkDocs 托管下的断链问题,读者可直达仓库运行指南;关于界面可视化检查 visual_review 为 not_applicable(reason: 仅修改 Markdown 外链目标,无桌面或 Web UI 布局改动;unverified_scope: none)。
  • 体量与兼容性(code_volume):仅 1 个文档文件 +3/-2 行;compatibility_assessment 为 not_applicable(无运行时接口或持久化兼容面)。
  • 词汇分类判断:未新增、扩展或改动任何状态词表。
  • 残余风险(Residual Risk):本地 .venv 未安装 mkdocs,未在本地运行完整 mkdocs build --strict;其余文档治理、边界扫描与源文件校验均在当前 head 通过。

评审精确提交:9032@1254f7598cf9a2882c4d8a75e6cb54a433c9c41e。

English Verdict: APPROVE

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · gpt-6.2-sol · OpenAI (runtime_reported, xhigh)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

动机 / Motivation

从官网阅读 Turn Envelope 参考文档、需要打开 benchmark 运行指南的读者。 原相对链接越过 MkDocs 的 docs 目录,严格构建报一处找不到目标的警告并中止发布。 候选改为原仓库指南的 HTTPS 链接。严格构建能产出文档,读者也能从同一段落打开指南。 本次验证文档产出和链接目标,未部署 Pages,也未运行 benchmark 或验证公开运行时资格。 链接指向主干的现行指南。Pages 发布和版本化运行时验收仍有各自的流程。

改动思路 / Approach

MkDocs 继续生成站内文档,仓库继续维护 benchmark 指南。只修链接目标,无需将指南复制进站点源码或放宽严格构建。 通过现有 Frontstage 文档入口生成真实站点,沿原路打开对应页面并读取生成后的链接。比较旧基线、精确头和当前主干整合,核实修改只将读者导向内容所有者。 适用规范

具体改动 / Changes

修改范围是单文件新增 3 行、删除 2 行,精确头 1254f7598cf9a2882c4d8a75e6cb54a433c9c41e,基线 4a0188c1ca1b6e33a11a7e31ddb56315bc1cdd46。与主干 871cc36348 干净整合。仓库现有工作流要求站点、中文书、英文书各自用严格模式构建。本次三个构建入口在精确头都通过,整合树的站点也通过。 构建契约

关键内容讲解

  • 指南链接。benchmark worker 段落保留读取历史 Turn Envelope、预览和资格回执的说明,只改变运行指南的链接。生成的网页在精确头与主干整合树都包含同一个 HTTPS 目标。 段落改动
  • 严格构建通过后读回目标。目标仍是仓库中的实际指南。独立读取 GitHub 源,确认 main 上文件存在,返回的文件对象与所核对的主干一致。 运行指南

对主干的风险 / Risks

同一份 MkDocs 依赖和命令在旧基线及现主干都复现恰好一条找不到 benchmark 路径的警告。精确头的站点和两本书、当前主干整合站点均通过。quick premerge 通过 4 项直接检查及 1 项公开边界检查。链接解析和目标已经读回,实际 Pages 部署仍待原发布流程。 未查询托管 CI。本次验证文档产出和链接目标,未部署 Pages,也未运行 benchmark 或验证公开运行时资格。

我的整体评价 / Verdict

APPROVE。 文档引用恢复,修复了原严格构建中止的具体原因,并保留原指南及核验边界。 链接指向主干的现行指南。Pages 发布和版本化运行时验收仍有各自的流程。

English verdict: APPROVE at 1254f75. Strict MkDocs reproduces the broken link on the base and current main, while the exact site, both books, and the integrated site pass. The rendered GitHub guide target was verified.

@mergify

mergify Bot commented Nov 21, 2026

Copy link
Copy Markdown

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @loopx-agent.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

@mergify mergify Bot added the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 21, 2026
@loopx-agent
loopx-agent merged commit ab55bbc into main Nov 21, 2026
4 of 7 checks passed
@loopx-agent
loopx-agent deleted the codex/fix-turn-envelope-benchmark-guide-20261118 branch November 21, 2026 14:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-rebase Mergify: the pull request has merge conflicts with its base branch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant